home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The PC-SIG Library 9
/
The PC-SIG Library on CD ROM - Ninth Edition.iso
/
1701_800
/
DISK1713
/
DISK1713.ZIP
/
QBSCR4.DOC
< prev
next >
Wrap
Text File
|
1990-04-11
|
74KB
|
1,949 lines
Subprogram PUTSCREEN
-------------------------------------------------------------
Purpose: The PutScreen routine will retrieve from
disk a premade screen file (generated with
GetScreen or Screen Builder) and place it on the
display. The whole operation takes less than a
second on a hard disk.
Usage: PutScreen file$
file$ - the disk file that is the screen
to be displayed
Details: This routine is the mechanism whereby
screens that are generated via the GetScreen
routine or the Screen Builder program are placed on
the screen. Simply make a call to PutScreen and it
will load the file from disk and shove it directly
into screen memory. The result is a very fast
display of a premade display.
When you call PutScreen, you send it the name of
the file that stores the screen you want to
display. PutScreen will quickly display it. Study
the example to see just how easy it is.
Example: This example will load a screen that was
previously generated using Screen Builder, and
display it. The screen was saved in a file called
SCREEN01.CLR.
' PutScreen example begins
' Load the screen and display it
PutScreen "SCREEN01.CLR"
' PutScreen example ends
End User Instructions: None.
Known Limitations: Works only with QBSCR Screen
Builder or GetScreen generated screens.
page 71
Subprogram QBPRINT
-------------------------------------------------------------
Purpose: Provides an combination of the print,
locate, and color statements in one command. Use
for the print instances where you need to print
characters that PRINT cannot handle, such as ASCII
7, the round bullet.
Usage: QBPrint st$, row%, col%, fore%, back%
st$ - the string or string expression to
be printed
row% - the row of the screen to locate
the string
col% - the column of the screen to locate
the string
fore% - the foreground color in which to
display the string
back% - the background color in which to
display the string
Details: This routine is most useful when you need
to either
- Display a string that has a character(s)
that the QuickBASIC PRINT statement cannot
handle, such as ASCII 7 ( CHR$(7) ). If you
try to say PRINT CHR$(7) to print the round
bullet ASCII character, the speaker will
beep instead, since ASCII 7 is also the bell
character.
- You want to print something in a different
color without having to issue a COLOR
statement. This routine will print a string
in a different color without changing the
current COLOR setting.
- You want to print a string without changing
the current cursor position. This routine
will print at an screen location without
changing the program's current cursor
position.
The QBPrint routine can do this because it writes
your string directly to the display board's memory.
That's why you can print ASCII 7 as a bullet, put
color values into video memory without changing
BASIC's color settings, and locate without moving
the cursor.
page 72
QBPrint supports all screen locations for the
LOCATE portion of its capability, foreground colors
from 0 to 31, and background colors from 0 to 7.
Example: This code segment will display a string
expression on line 10, column 25, with a bright
white foreground and a blue background. It is
broken onto two lines due to the column width.
' QBPrint example begins
' Print a string with characters only QBPrint
' can handle
QBPrint CHR$(7) + " A bulleted string", 10, 25,
15, 1
' QBPrint example ends
End User Instructions: None.
Known Limitations: QBPrint is a little slow when it
comes to printing an entire screen of information.
Use it sparingly, and only when necessary. In this
manner, it will be a valuable tool to have around.
page 73
Function SCREENBLANK
-------------------------------------------------------------
Purpose: Provides a screen saver feature to any
program to prevent image "burn-in."
Usage: x$ = ScreenBlank$(delay)
x$ - Any string variable that will
contain the key that was pressed
during the screen blank.
delay - A numerical value that
represents the amount of time to
wait between screen blanker
message shifts.
Details: If your application program leaves the
same image on the screen for any extended period of
time, the image may become "burned in" to the
screen. The result is a ghost image of the display
forever left on the monitor. To prevent this from
happening, you can blank the screen after a defined
period of inactivity. This will prevent the image
from "burning in". However, if the user later
returns and sees a blank screen, what are they to
think? Anything could be wrong with the computer.
What we need is a small message on the screen to
inform the user that the screen has been blanked
out, and they can hit any key to return to the
program. That seems to solve the problem but
there's one twist left: What's to prevent the small
message from itself burning into the screen? The
answer is surprisingly easy. We move the message
around on the screen at periodic intervals. Moving
the message, or "bouncing" it, is easy to do, and
the ScreenBlank routine takes care of all these
features for you.
When you call ScreenBlank, it is assumed that your
program has determined that a period of inactivity
of sufficient duration has elapsed. The delay
parameter is a counter. The larger the value, the
longer the wait between the movements of the
ScreenBlank message. A value of 100,000 is roughly
equal to 3 minutes on a 6 MHz AT-class machine. You
can experiment with the delay to see what suits you
and your machine.
page 74
Example: This example assumes you are checking for
activity in your program. The code that you would
execute if activity occurs is only commentary in
this example. We are representing the main loop
for any program here. The example checks for any
user activity (usually keystrokes). If there is
something to do, it executes any code necessary.
Otherwise, it increments a counter we are using
called wait. The wait counter is used to determine
if the desired period of inactivity has elapsed.
If wait ever reaches our preset limit, we go into
the ScreenBlank. The key pressed by the user to
exit the ScreenBlank is stored in x$, but since we
don't need it here we'll just ignore it.
' ScreenBlank example begins
' Now sitting in some kind of loop
wait = 0: maxWait = 100000
DO
IF AnyUserActivity THEN
' Execute any code necessary
wait = 0
ELSE
wait = wait + 1
IF wait > maxWait then
wait = 0
x$ = ScreenBlank$(50000)
END IF ' wait > maxWait
END IF ' AnyUserActivity
LOOP UNTIL UserQuits
' ScreenBlank example ends
End User Instruction: To return to the main program
(i.e., to exit the ScreenBlank function), the user
can hit any key.
Known Limitations: The delay counter uses a
floating point value (single precision real), so
the delay parameter is limited to the maximum value
for single precision reals.
page 75
Subprogram SCRNRESTORE
-------------------------------------------------------------
Purpose: To restore a portion or all of the screen
saved with the QBSCR SCRNSAVE routine.
Usage: ScrnRestore firstLine%, lastLine%,
scrArray%(), segment
firstLine% - The first line of the
screen to restore.
lastLine% - The last line of the screen
to restore.
scrArray%() - An integer array that
stores the information saved from
the screen via SCRNSAVE. See
below for more information.
segment - The beginning address of
video memory. Use the QBSCR
routine GETVIDEOSEGMENT to obtain
this. See below for details.
Details: Before you use the SCRNRESTORE routine,
you have to have something to restore to the
screen. In the normal course of events you would
save a portion or all of the screen using the
SCRNSAVE routine, display something over the
existing screen like a window, and then restore the
screen when finished with the window using
SCRNRESTORE.
To use the SCRNRESTORE routine, we can assume you
have saved a part or all of the display using
SCRNSAVE. There are points that need to be
understood before either the SAVE or RESTORE can be
used. The first is that when you save part of the
screen, the information saved is stored in an
array. The array must be an integer array, and it
must have 4000 elements. To dimension such an
array, use the following sort of DIM statement:
DIM scrArray%(4000)
This provides you an array in which to store the
screen information. This array is passed to the
SCRNRESTORE (or SAVE) routine, so that that it has
something to read from (or store to).
The second concept of importance is that the
SCRNRESTORE (and SAVE) routine know the location of
page 76
the beginning of the video card memory. This is
simply a value, and it can easily be obtained using
the GETVIDEOSEGMENT function in the QBSCR package.
All you have to do is obtain a segment value using
this function, like this:
segment = GetVideoSegment
And then pass the segment parameter to the
SCRNRESTORE (or SAVE) routine, like this:
ScrnRestore 1, 25, scrArray%(), segment
The first and last lines specify the range of lines
on the screen to actually save. The example above
would save the entire screen (lines 1 through 25).
See the example below for usage.
Example: This example uses the SCRNSAVE routine to
save a part of the screen. An error message is
then displayed over the screen. Finally, the
screen is restored with SCRNRESTORE when the user
hits a key.
' ScrnRestore example begins
' Dimension an array to store the screen contents
DIM scrArray%(4000)
' Assign first and last line parameters for both
' SAVE and RESTORE (they are the same). Saving
' only the lines that will be overwritten by the
' error message.
first% = 11
last% = 15
' Obtain the proper video memory segment
segment = GetVideoSegment
' Save the designated portion of the screen
ScrnSave first%, last%, scrArray%(), segment
' Display the error message - this code commented
' out. You would display something on the screen
' on lines 11 through 15.
' Wait for a keypress.
keyPress$ = INPUT$(1)
' Restore the screen after the user hits a key.
ScrnRestore first%, last%, scrArray%(), segment
' ScrnRestore example ends
page 77
For more information in the form of examples, see
the source code for the DEMO program or the
Techniques section of this manual.
End User Instructions: None.
Known Limitations: None.
page 78
Subprogram SCRNSAVE
-------------------------------------------------------------
Purpose: To save a portion or all of the screen
before overwriting it with something else.
Usage: ScrnSave firstLine%, lastLine%,
scrArray%(), segment
firstLine% - The first line of the
screen to save.
lastLine% - The last line of the screen
to save.
scrArray%() - An integer array that
stores the information saved from
the screen.
segment - The beginning address of
video memory. Use the QBSCR
routine GETVIDEOSEGMENT to obtain
this. See below for details.
Details: In the normal course of events you would
save a portion or all of the screen using the
SCRNSAVE routine, display something over the
existing screen like a window, and then restore the
screen when finished with the window using
SCRNRESTORE.
There are points that need to be understood before
either the SAVE or RESTORE can be used. The first
is that when you save part of the screen, the
information saved is stored in an array. The array
must be an integer array, and it must have 4000
elements. To dimension such an array, use the
following sort of DIM statement:
DIM scrArray%(4000)
This provides you an array to store the screen
information. This array is passed to the
SCRNSAVE (or RESTORE) routine, so that that it has
something in which to save the screen information.
The second concept of importance is that the
SCRNSAVE (and RESTORE) routine know the location of
the beginning of the video card memory. This is
simply a value, and it can easily be obtained using
the GETVIDEOSEGMENT function in the QBSCR package.
All you have to do is obtain a segment value using
this function, like this:
page 79
segment = GetVideoSegment
And then pass the segment parameter to the
SCRNSAVE (or RESTORE) routine, like this:
ScrnSave 1, 25, scrArray%(), segment
The first and last lines specify the range of lines
on the screen to actually save. The example above
would save the entire screen (lines 1 through 25).
See the example below for usage.
Example: This example uses the SCRNSAVE routine to
save a part of the screen. An error message is
then displayed over the screen. Finally, the
screen is restored with SCRNRESTORE when the user
hits a key.
' ScrnSave example begins
' Dimension an array to store the screen contents
DIM scrArray%(4000)
' Assign first and last line parameters for both
' SAVE and RESTORE (they are the same). Saving
' only the lines that will be overwritten by the
' error message.
first% = 11
last% = 15
' Obtain the proper video memory segment
segment = GetVideoSegment
' Save the designated portion of the screen
ScrnSave first%, last%, scrArray%(), segment
' Display the error message - this code commented
' out. You would display something on the screen
' on lines 11 through 15.
' Wait for a keypress.
keyPress$ = INPUT$(1)
' Restore the screen after the user hits a key.
ScrnRestore first%, last%, scrArray%(), segment
' ScrnSave example ends
For more information in the form of examples, see
the source code for the DEMO program or the
Techniques section of this manual.
page 80
End User Instructions: None.
Known Limitations: None.
page 81
Function SELECTLIST
-------------------------------------------------------------
Purpose: The SelectList function accepts an array
of strings and creates from it a scrolling list
with selection bar. The user may scroll through
the list and select one of the choices. The
function returns the user selection as a string.
Usage: choice$ = SelectList$(items$(), numItems%,
topRow%, botRow%, leftCol%,
maxWidth%, normFG%, normBG%,
hiFG%, hiBG%)
items$() - a string array containing
the items in the list from
which a selection will be
made
numItems% - The number of items in the
list
topRow% - the top-most row of the
screen on which the list
will be displayed
botRow% - The bottom-most row of the
screen on which the list
will be displayed
leftCol% - The left-most column of
the screen on which the
list will be displayed
maxWidth% - The length of the longest
string in the list
normFG% - The foreground color of
normal list choices
normBG% - The background color of
normal list entries
hiFG% - The foreground color of the
highlighted list entry
hiBG% - The background color of the
highlighted list entry
Details: With this function, you can make a
scrolling selection list from almost any set of
string data, such as file names. The
possibilities all depend on the functionality of
your program.
The basic steps to setting up a scrolling selection
list are
1) DIMension an array to hold list choices
page 82
2) Fill in list choices in the array
3) Call SelectList
4) Use the value returned by SelectList
Let's step through the procees in detail by
contriving an example. We will using as our
example the color setup portion of a program. We
will be presenting to the user a scrolling list of
color choices. There are sixteen possible colors,
and we only have room on our display for a list
that is 8 lines in height. Therefore, a scrolling
list will be just the ticket.
Step 1: Dimension an array to hold our list of
choices. This can be done in a second or two.
Simply DIM a string array with the maximum number
of list entries. In our example, we have sixteen
possible choices, so our code would look like this
in QuickBASIC:
maxChoices% = 16
DIM colors$(maxChoices%)
Step 2: Fill in the choices in the array we just
created. This is the only vaguely tedious part of
making a list, but you'd have to type them in one
way or another. Fill in our color choices like
this:
colors$(1) = "Black"
colors$(2) = "Blue"
colors$(3) = "Green"
colors$(4) = "Cyan"
colors$(5) = "Red"
colors$(6) = "Magenta"
colors$(7) = "Brown"
colors$(8) = "White"
colors$(9) = "Dark Gray"
colors$(10) = "Bright Blue"
colors$(11) = "Bright Green"
colors$(12) = "Bright Cyan"
colors$(13) = "Bright Red"
colors$(14) = "Bright Magenta"
colors$(15) = "Yellow"
colors$(16) = "Bright White"
Step 3: Make the call to SelectList. We need to
tell SelectList some additional information as well
the list itself. It needs to know the number of
page 83
items in the list (16), the width of the longest
choice (Bright Magenta, 14 characters), and where
we want it on the screen. We'll be placing it
between rows 11 and 16. This provides only six
lines for the list, but we have to allow for the
top and bottom lines of the window we'll be placing
it in. The list will start at column 10. The list
be have a foreground color of bright white and
background color of red, while the highlighted
entry will be yellow on a black background. So,
we'll be making a window first to place the list in
(using MakeWindow), and then calling SelectList.
Our QuickBASIC code looks like this:
' Make a window for the list
MakeWindow 10, 9, 17, 26, 15, 4, 0, 0, -1, 0, ""
' Call SelectList
colorChoice$ = SelectList$(colors$(), maxChoices%,
11, 16, 10, 14, 15, 4, 14, 0)
SelectList now takes over and the user may select
which color they would like. Once a color choice
is made, the string chosen is returned and stored
in colorChoice$. If the user hit ESC and no choice
was made, SelectList will return a nul string ("").
Make sure to look at the notes on End User
Instructions to see all the movement capabilites of
SelectList.
Example: This example will simply pull together our
above example.
' SelectList example begins
' DIMension an array to store list choices
maxChoices% = 16
DIM colors$(maxChoices%)
' Fill in the choices in the array
colors$(1) = "Black"
colors$(2) = "Blue"
colors$(3) = "Green"
colors$(4) = "Cyan"
colors$(5) = "Red"
colors$(6) = "Magenta"
colors$(7) = "Brown"
colors$(8) = "White"
colors$(9) = "Dark Gray"
colors$(10) = "Bright Blue"
page 84
colors$(11) = "Bright Green"
colors$(12) = "Bright Cyan"
colors$(13) = "Bright Red"
colors$(14) = "Bright Magenta"
colors$(15) = "Yellow"
colors$(16) = "Bright White"
' Make a window for the list
MakeWindow 10, 9, 17, 26, 15, 4, 0, 0, -1, 0, ""
' Call SelectList
colorChoice$ = SelectList$(colors$(), maxChoices%,
11, 16, 10, 14, 15, 4, 14, 0)
' You could now do whatever you wanted to with the
' User's selection.
' SelectList example ends
End User Instructions: SelectList has a complete
host of movement operations available to the user.
The following table lists the operations provided
and the keys used to execute them.
SelectList Operation... ...Key(s)
--------------------------------------------------
Move list/highlight up one line . . . . Up Arrow
Move list/highlight down one line . . Down Arrow
Move list/highlight up one screen . . . . . PgUp
Move list/highlight down one screen . . . . PgDn
Move list/highlight to top of list . . . . . Home
Move list/highlight to bottom of list . . . . End
Select highlighted choice . . . . . . . . . Enter
Abort selection . . . . . . . . . . . . . . . Esc
The user may also hit any letter or number key. If
there is a choice in the list whose first character
is the same as the letter/number hit, the highlight
and list will move immediately to it.
Known Limitations: String entries in the list must
be 78 characters or less in length. The maximum
visible portion of the list is the entire screen.
Number of entries is limited by available string
space in your program.
page 85
Subprogram VIEWLIST
-------------------------------------------------------------
Purpose: Provides a scrolling list of text on the
screen from a passed in string array.
Usage: ViewList list$(), listLen%, maxWidth%,
topRow%, botRow%, leftCol%, fg%, bg%
list$() - The array of strings to be
treated as a scrolling list
listLen% - The number of lines in the
list (elements in the
string array)
maxWidth% - The width of the longest
string in the array
topRow% - The top-most row of the
screen on which the list
will be displayed
botRow% - The bottom-most row of the
screen on which the list
will be displayed
leftCol% - The left-most column of the
screen on which the list
will be displayed
fg% - The foreground color of the list
bg% - The background color of the list
Details: ViewList creates, from a string array
passed in, a scrolling list of text with a full
compliment of movement operations. The basic steps
involved in creating a scrolling list are:
1) DIMension an array to hold the text
2) Fill the array with text
3) Call ViewList
To explain the workings of ViewList, we'll make up
an example to go through. Our example will be a
help text viewer. We will use viewlist to display
a small window in which help text may be scrolled.
Our window and text will be yellow on a blue
background, will be positioned between rows 5 and
10 on the screen, and will be about 40 columns
wide.
page 86
Step 1: DIMension an array to hold the text. We
need a string array to hold the text to be scrolled
through. Assume our text will be no more than 25
lines. Our QuickBASIC code will look like this:
maxLines% = 25
DIM txt$(maxLines%)
Step 2: Fill the array with text. This is the part
where we do the bulky typing. You could enter the
text and store it permanently in your program (as
we will in this example), or you could read it in
from a data file on disk. The disk file method
will save you a great deal of string space, but
will be somewhat slower, as it takes time to read
from disk.
txt$(1) = "This help text is designed to"
txt$(2) = "guide you through the process"
txt$(3) = "of installing the QBSCR Screen"
txt$(4) = "Routines on your hard disk."
txt$(5) = ""
txt$(6) = "Step 1: Make a subdirectory on"
txt$(7) = "your hard disk. You can call"
txt$(8) = "it whatever you like. In this"
txt$(9) = "example, it will be C:\QBSCR."
txt$(10) = "The DOS command looks like"
txt$(11) = "this: MD C:\QBSCR"
txt$(12) = ""
txt$(13) = "Step 2: Copy all the files"
txt$(14) = "from the distribution disks"
txt$(15) = "to the subdirectory you made"
txt$(16) = "in step 1. The DOS command"
txt$(17) = "for our example, assuming the"
txt$(18) = "floppy drive is A: would be:"
txt$(19) = "COPY A:*.* C:\QBSCR"
txt$(20) = ""
txt$(21) = "Step 3: Repeat this process"
txt$(22) = "for each of the QBSCR disks."
txt$(23) = ""
txt$(24) = "Once this is done, QBSCR is"
txt$(25) = "ready to go!"
Step 3: Make the call to ViewList. A single
statement at this point calls ViewList to create
the scrolling list. First, however, we will make a
window in which the list will be placed, using
MakeWindow.
' Make a window for the help text
MakeWindow 5, 5, 10, 45, 14, 1, 0, 0, -1, 0,
" Installation Help "
page 87
' Call ViewList
ViewList txt$(), maxLines%, 36, 11, 14, 6,
14, 1
From this point, ViewList is in control. Once the
usert hits ESC to quit, control is returned to your
calling routine. Nothing is returned or changed.
Example: This example will simply pull together our
above example into one piece.
' ViewList example begins
' DIMension an array to hold text
maxLines% = 25
DIM txt$(maxLines%)
' Fill the array with the text to view
txt$(1) = "This help text is designed to"
txt$(2) = "guide you through the process"
txt$(3) = "of installing the QBSCR Screen"
txt$(4) = "Routines on your hard disk."
txt$(5) = ""
txt$(6) = "Step 1: Make a subdirectory on"
txt$(7) = "your hard disk. You can call"
txt$(8) = "it whatever you like. In this"
txt$(9) = "example, it will be C:\QBSCR."
txt$(10) = "The DOS command looks like"
txt$(11) = "this: MD C:\QBSCR"
txt$(12) = ""
txt$(13) = "Step 2: Copy all the files"
txt$(14) = "from the distribution disks"
txt$(15) = "to the subdirectory you made"
txt$(16) = "in step 1. The DOS command"
txt$(17) = "for our example, assuming the"
txt$(18) = "floppy drive is A: would be:"
txt$(19) = "COPY A:*.* C:\QBSCR"
txt$(20) = ""
txt$(21) = "Step 3: Repeat this process"
txt$(22) = "for each of the QBSCR disks."
txt$(23) = ""
txt$(24) = "Once this is done, QBSCR is"
txt$(25) = "ready to go!"
' Make a window for the help text
MakeWindow 5, 5, 10, 45, 14, 1, 0, 0, -1, 0,
" Installation Help "
' Call ViewList
ViewList txt$(), maxLines%, 36, 11, 14, 6,
14, 1
' ViewList example ends
page 88
End User Instructions: ViewList provides a
comprehensive set of movement commands for the
user. The following list describes the operations
available as well as the keys that execute them.
Opeartion... ...Key(s)
---------------------------------------------------
Move up one line . . . . . . . . . . . . . Up Arrow
Move down one line . . . . . . . . . . . Down Arrow
Move up one screen . . . . . . . . . . . . . . PgUp
Move down one screen . . . . . . . . . Enter, PgDn
Move to top of list . . . . . . . . . . . . . Home
Move to end of list . . . . . . . . . . . . . End
Abort viewing . . . . . . . . . . . . . . . . Esc
Known Limitations: The amount of text that can be
displayed is limited by the amount of available
string space.
page 89
Subprogram WIPE
-------------------------------------------------------------
Purpose: To clear a programmer-defined portion of
the screen.
Usage: Wipe top%, bottom%, lft%, rght%, back%
top% - The top-most row to clear
bottom% - The bottom-most row to clear
lft% - The left-most column to clear
rght% - The right-most column to clear
back - The background color with
which to clear the screen.
Details: The Wipe routine is used to clear selected
portions of the screen. It is particularly useful
for clearing the contents from existing windows so
that they can be reused.
All you need do to use Wipe is to specify the left,
right, top, and bottom coordinates of the
rectangular area to clear. Wipe will always clear
the INSIDE of the area you specify. In other
words, if you tell it to clear an area where
top% = 5
bottom% = 10
lft% = 10
rght% = 70
Wipe would actually clear an area of
top% = 6
bottom% = 9
lft% = 11
rght% = 69
It does this so that if you have a window to clear
out, you can call Wipe with the same coordinates as
your window without erasing your screen border.
Makes using Wipe much easier.
The back% parameter indicates the color to use when
clearing out the defined area, and should be the
same color as the existing background.
page 90
Example: The following example will assume we have
a window at the above listed coordinates, and we
wish to clear it out for reuse. The background
color of this window is blue.
' Wipe example begins
' Set our parameter variables for area to clear
top% = 5
bottom% = 10
lft% = 10
right% = 70
' Set our background color with which to clear
back% = 1 ' Blue
' Wipe the area clear
Wipe top%, bottom%, lft%, rght%, back%
' Wipe example ends
End User Instructions: None.
Known Limitations: None.
page 91
Techniques for Using QBSCR
-------------------------------------------------------------
Since providing documentation for the routines
won't tell you how to perform specific tasks, this
manual has this section which details some of the
techniques possible with the QBSCR routines.
The techniques described in here will not only
clarify the usage of some of the routines, but will
also show you how to combine the routines to
accomplish specific tasks. These techniques will
add professionalism to any program that yearns for
it.
Simply choose the section you have interest in, and
the documentation will attempt to detail the
technique in terms of why it is used, what it can
do for you, and how to do it.
page 92
Displaying and Popping a Window from the Screen
-------------------------------------------------------------
Many programs add professionalism to their
appearance using this technique. The effect can be
described as laying a window on top of an existing
display and when its usefulness has elapsed, it is
"popped," or quickly removed from the screen, and
the underlying display remains intact. While this
is what appears to happen, the mechanics are a bit
different.
This is what actually happens:
1) The initial display exists on the screen.
2) The contents of the video card memory,
which contains the text on the screen and
the color attribute of each character, is
saved inside the program (in our case, in
an integer array).
3) The new window is is written to the display
overwriting and destroying the portion of
the display it now occupies.
4) When the window is to be removed or popped
from the screen, what actually happens is
that the contents of the video memory saved
in step 2 before the new window was
displayed is now restored to video memory.
This causes the old saved information to be
redisplayed.
The window has been effectively displayed and then
popped from the display when it was no longer
needed. We can easily perform this task with the
QBSCR Screen Routines. Specifically, we will need
the services of the SCRNSAVE, MAKEWINDOW, and
SCRNRESTORE routines. The same step-by-step
process above applies here:
1) Display the initial screen. This can be
displayed during the normal course of
program execution. Any existing display
can be saved/restored.
2) Save the screen contents into an integer
array using the SCRNSAVE routine.
3) Place the new window on the screen using
the MAKEWINDOW routine. You can then print
any text inside the window you need.
page 93
4) As soon as you are finished with the
window, you can restore the original screen
contents, thus popping the window off the
display, using the SCRNRESTORE routine.
The use of windows is extremely useful for
isolating a single thought, concept or activity on
your display screen. Using this technique will
allow you to use windows while retaining the
integrity of the underlying screen. This will
result in much faster execution time and happier
users, since you and they don't have to wait to
redraw the whole screen.
We'll now go through a practical example of the
entire process. To use an earlier example, our
task is to display an error message in the middle
whatever screen currently exists on the display.
Who knows when an error will come up? We will
assume that there is some sort of event that
triggers the error - we're only going to worry
about displaying the error in a window and then
restoring the display. Other assumptions are:
1) The error message will never be more than 5
lines long, each of which will be 60
characters or less in length. This means
we will need 7 display lines (5 lines of
error text + 2 lines for the window frame).
2) The user will hit a key to clear the error
message window from the screen, signifying
that they are finished reading it.
3) The software will be running on a color
display.
4) There will be a routine called ErrorMessage
that will place the appropriate text for
the error message inside our window.
So let's begin our example. The code here will be
commented well so that it is clear what's
happening.
' Window display/removal example begins
' Dimension an array to store screen contents
DIM scrArray%(4000)
page 94
' Save the portion of the screen we will be
' overwriting. Our window will always be
' located between rows 10 and 16. First
' though, we need the proper video segment.
segment = GetVideoSegment
' Now we can save the portion of the screen we will
' be overwriting.
ScrnSave 10, 16, scrArray%(), segment
' We've now paid our insurance - lets display the
' error message window. We will assign our window
' parameters as variables for readability.
leftCol = 8: rightCol = 73
topRow = 10: botRow = 16
foreColor% = 15 ' Bright White
backColor% = 4 ' Red
windowType% = 0 ' Normal window, no inside lines
frameType% = 1 ' All double lines
shadowColor% = 0 ' Black window shadow
explodeType% = 1 ' Automatic explode mode
label$ = " Error! "
' Make the window on the screen. Note that in your
' real program this next statement would be on a
' single line.
MakeWindow topRow, leftCol, BotRow, rightCol,
foreColor%, backColor%, windowType%,
frameType%, shadowColor%, explodeType%,
label$
' Add the error text to the window. We will assume
' that there is a routine called ErrorMessage that
' will place the correct message at the right spot
' on the screen.
ErrorMessage
' Wait for the user to hit a key, signifying that
' they are finished with the message.
keyPress$ = INPUT$(1)
' Now that the user is done, we will restore the
' screen to the state it was in before the error
' message window was displayed using SCRNRESTORE.
ScrnRestore 10, 16, scrArray%(), segment
' Window display/removal example ends
Note that you should only save and restore the
smallest amount of the screen as you need to. Doing
so will result in much faster performance.
page 95
This technique can be used for multiple windows
simultaneously by having an integer array for each
window you place on the screen. Save the screen
with a new array each time you add a new window to
the screen. In this way, you can reverse the order
when you restore screens, and the windows will be
removed from the display one at a time in order.
page 96
Visual Effects with BUILDSCREEN and CLRSCR
-------------------------------------------------------------
BuildScreen and ClrScr are complimentary routines.
Although one creates screens and the other destroys
them, they perform these tasks in the same way. If
you look at the source code for each routine,
you'll see that they are very similar. Each
routine also supports exactly the same modes of
animation. ClrScr mode 10, for example, will clear
the screen in a spiral fashion, while BuildScreen
mode 10 displays a screen in the same spiral
fashion.
Since the modes of animation are the same for each
routine, they can be used together to create
interesting visual effects. A perfect example is
demonstrated in the DEMO program. This example
uses complimentary ClrScr and BuildScreen routines.
ClrScr is used to first clear the screen using
ASCII character 176 (░) with mode 3, which
resembles curtains closing on a stage. Then the
display is placed on the screen using BuildScreen
mode 2, which is the complimentary opposite mode of
mode 3 just used with ClrScr. The effect looks
likes curtains closing on the existing display, and
the curtains open again revealing the new display.
Techniques like this can be generated easily for
opening screens of programs or other displays. For
details on the example described above, see the
source code for the DEMO program. Other modes that
match well can be used to create similar effects.
Use the REF program to see all the ClrScr and
BuildScreen modes. By playing around a bit, you
may discover an impressive way to open your own
program.
page 97
Window Making Techniques
-------------------------------------------------------------
Creating a "Frameless" Window
---------------------------------------------------
Sometimes you don't want a border, or frame, around
your window. You just want a colored field. You
can do this two ways.
The first and most obvious method is to use the
MakeWindow routine. You can do this easily by
making the foreground and background color
parameters the same value. If for instance you
wanted to make a red frameless window, simply make
the foreColor and backColor parameters the same, in
our case, 4. It doesn't matter what the frameType
or windowType parameters are since you won't see
them. Choose any valid value such as zero for both
parameters.
The drawback with this technique is that you must
provide all the MakeWindow parameters. There is a
shortcut for creating a frameless window. You do
so by using the Wipe routine. Simply pass Wipe the
coordinates for your window and a color for the
field. This results in the much easier creation of
a frameless window.
Of course, if you want a shadow for the window, or
you want it to explode onto the screen, the first
option is your best bet. Frameless windows, by the
way, look great with a black shadow.
Window Shadows
---------------------------------------------------
And speaking of window shadows, the new shadow mode
that MakeWindow incorporates will add a definite
touch of professionalism to any program that uses
windows.
The new shadow types are 16 and 17, and will leave
existing characters in the shadowed region on the
screen. It will, however, change the color of the
characters so they are in plain white (for mode
16), or low-intensity versions of existing colors
(using mode 17). This is exactly the same shadowing
that the QuickBASIC environment uses (mode 16), and
looks very sharp. If you plan to be using color
displays, then seriously consider either shadow
mode.
page 98
Menu Techniques
-------------------------------------------------------------
Producing a Clear and Clean Menu
---------------------------------------------------
When generating menus for a person to use, it's
important to keep a couple of design concepts in
mind.
Your menus should be easy to use and understand.
This means keeping the menu focused without too
many choices. Users tend to work best when they
have nine or fewer choices to decide between. The
choices themselves should be concise yet distinct.
There shouldn't be any question about what a
particular entry does. You can accomplish these
goals by giving your entries careful thought. Make
sure each is meaningful, and keep your menu choices
to as few as possible.
There are specific things you can do with the QBSCR
MakeMenu function to further these aims.
1) Keep your menu entries to a minimum and
make sure they are clear.
2) Use "Quick Access" keys to make your menus
easier to use. By providing both a
selection bar and Quick Access keys, you
satisfy the needs of both the novice and
the advanced user.
3) Choose your Quick Access Keys carefully.
Specifically, choose ones that are easy to
remember. For instance, if your entry is
"Save File," the S would make an excellent
Quick Access key, since S is closely
related to the primary function of the
entry, Saving a file. The V wouldn't be
terrible, but the F would be the worst,
since you might also have "Edit File" and
"Load File" entries. The F would not
distinguish the Save function from any of
the other file operations.
4) Always provide on-screen instructions on
how to use the menu.
page 99
5) Keep your menus clean. Isolate them from
any other distracting screen information.
You can do this by
a) choosing a location on the screen
that is as removed as possible from
other information on the screen,
and
b) placing your menu inside a window.
If you place your menu inside a window, it
isolates the menu even further from the
rest of the world. This will help the user
focus on the menu and the decision to be
made there.
While all these ideas may sound odd or picky, they
all come together to make your menus more
presentable, easy to use, and professional. The
user may not be thinking "Wow, this menu is nicely
isolated and that makes it easier for me to deal
with," but it inherently will be. Their overall
impression will be more favorable, even if they
don't specifically know why. They should at least
get the impression that the program is well
organized.
page 100
Cross Reference - Routine Dependencies
-------------------------------------------------------------
To make code more efficient, some of the QBSCR
routines make use of each other's services. This
section of the documentation will detail exactly
what routines are dependent on others, and on which
ones. Consult this table carefully if you plan to
be pruning off routines your particular program
will not be using.
Also note that there are two routines in the QBSCR
package that are not documented except here. They
are the function SubMenu and the subprogram
DisplayEntry. They are used only internally by
other routines, which are detailed below.
Routine... ...is dependent on
---------------------------------------------------
Banner . . . . . . . . . . . . . . . . . . . . none
BlockRestore . . . . . . . . . . . . . . . . . none
BlockSave . . . . . . . . . . . . . . . . . . none
BlockSize . . . . . . . . . . . . . . . . . . none
BuildScreen . . . . . . . . . . . GetVideoSegment
Center . . . . . . . . . . . . . . . . . . . . none
ClrScr . . . . . . . . . . . . . . . . . . . . none
ColorChk . . . . . . . . . . . . . . . . . . . none
DisplayEntry . . . . . . . . . . . . . . . . . none
EditString . . . . . . . . . . . . . . . . ColorChk
GetBackground . . . . . . . . . . GetVideoSegment
GetForeground . . . . . . . . . . GetVideoSegment
GetScreen . . . . . . . . . . . . GetVideoSegment
GetVideoSegment . . . . . . . . . . . . . . . none
MakeMenu . . . . . . . . . . . . . . . DisplayEntry
MakeWindow . . . . . . . . . . . . GetVideoSegment
MultiMenu . . . . . . . . . . . . . . BlockRestore
BlockSave
DisplayEntry
GetVideoSegment
MakeWindow
SubMenu
OffCenter . . . . . . . . . . . . . . . . . . none
PutScreen . . . . . . . . . . . . GetVideoSegment
QBPrint . . . . . . . . . . . . . GetVideoSegment
ScreenBlank . . . . . . . . . . . . . . . . . none
ScrnRestore . . . . . . . . . . . . . . . . . none
ScrnSave . . . . . . . . . . . . . . . . . . . none
SelectList . . . . . . . . . . . . . . . . . . none
SubMenu . . . . . . . . . . . . . . . DisplayEntry
ViewList . . . . . . . . . . . . . . . . . . . none
Wipe . . . . . . . . . . . . . . . . . . . . . none
page 101
Closing Notes
-------------------------------------------------------------
I sincerely hope that the QBSCR Screen Routines are
of some help to you, either in a productivity or a
tutorial capacity. The Screen Routines try their
best to fill both roles.
The BAD SOFTWARE Company has two missions in the
world of software for the IBM PC and compatibles.
The first is to provide useful software that's easy
to use. The primary purpose of any software is
that it does something you want or need. Therefore,
BAD SOFTWARE is dedicated to the development of
software that has these qualities. But the second
item of importance to BAD SOFTWARE is that software
be fun. Computing need not be a chore to avoid.
The QBSCR Screen Routines hopefully fulfill this
requirement. It's always been fun for me to make
my own programs appear as professional as possible,
and the Screen Routines let me do this while
expending very little time and effort. I can only
hope that they will do the same for you.
If you have any comments or ideas about the Screen
Routines, please feel free to drop me a letter at
the following address. I'll do my best to answer
all correspondence.
Tony Martin
1611 Harvest Green Ct.
Reston, VA 22090
Lastly, I must acknowledge a few copyrights.
Microsoft and QuickBASIC are trademarks of
Microsoft Corporation. I'm sure you didn't know
this...
page 102
Registration Form
-------------------------------------------------------------
If you decide to register the QBSCR Screen
Routines, send a check for $15.00 U.S. made out to
Tony Martin to:
Tony Martin
1611 Harvest Green Ct.
Reston, VA 22094
In return I will send you an official disk set
containing all the files of the latest version of
the Screen Routines. In addition you will receive
a free copy of the LASER II graphics entertainment
program written by BAD SOFTWARE exclusively for
registered users of BAD SOFTWARE products.
---------------------------------------------------
Complete this registration form and send with your
check to the above listed address.
Product: QBSCR Screen Routines
Version: 1.6
Cost $15.00
Quantity: ________
Total: $__________
Ship to:
Name: _____________________________________________
Address: __________________________________________
City/State/Zip: ___________________________________
page 103
